結束了八大詞類，今天開始會進入修辭篇：討論一些程式以外的東西：從寫註解開始。

為什麼要寫註解

註解是除了程式本身以外，少數在程式裡就能描述程式用途本身的功能。上個世紀以來就有許多前輩都說「寫註解的工程師，才是好工程師」。其實不難理解原因：以前的編輯器和編譯器功能非常單一，要在不同的函數中切換真的會查到懷疑人生，再加上簡化的命名，奇怪的結構，能在程式裡加上說明文字，放過自己，放過其他人。

Ref:https://hackaday.com/2018/02/22/quickbasic-lives-on-with-qb64/
但把時間推進到廿一世紀，各種語言快速的發展，方便的編譯器，以及神奇的語法，還有像Resharper之類的工具可以輔助開發人員。但開發人員還是用上個世紀的思維在寫程式，認為寫註解的工程師才是好工程師？
應該要寫，但要用比較具演進思維的方法寫註解。

怎麼寫註解

這不是要討論寫註解的語法，而是應該怎麼把註解寫好。
前面的二十幾天，都在討論怎麼把程式寫好，寫得通順，其實如果回過頭來看，會發現程式本身就可以表達方法或函數本身要達成的目的：有著清楚的命名，符合命名規則的變數，適度切分的方法並有著非常容易懂的方法名稱，每個方法的大小適中...這些其實都己經足夠取代過去寫註解的方法了。

但如果真的還是想寫，至少應該要有以下幾個重點：

1. Why, not how

寫註解最怕這種寫法：

    //跑一個foreach,讀每一場遊戲
    foreach(var game in games)
    {
        //呼叫SaveStatus
        game.SaveStatus();
    }

寫成這樣也沒有幫助

    //把每一場的status都存起來
    foreach(var game in games)
    {
        game.SaveStatus();
    }

因為程式碼本身就和註解語意相同，寫成這樣還不如寫成

    SaveStatus(games);

如果真的要寫註解，應該要把重點不是「怎麼寫」，而是放在「為什麼」。

    //在開新的比賽前，把所有的結果都先存起來。
    SaveStatus(games);

優秀的範例可以看這裡

2. Keep it simple and updated

註解絕對是一個傳達訊息的好地方，但如果需要大量的描述才可以精確的讓維護的人知道這個方法或系統怎麼使用：或許這是一個訊號：這段程式應該要重構了。

有些工程師喜歡把修改的記錄也放在註解裡，Hello～這是廿一世紀了，寫在Commit log裡好嗎？

另外還有一個重點，就是像這種註解：

/*
建立使用者
firstName : 名
lastName : 姓
*/
public bool CreateUser(string firstName, string lastName, Guid versionID){
...
}

這種情況就是，方法修改了，增加了一個新的參數，但註解卻沒有更新。所以如果真的想寫註解，註解也應該要隨著程式碼更新。
3. Be nice

維護別人的程式很累人吧！與其寫這種Comment

    //寫這個程式的人腦袋不知道裝什麼

不如花時間重構它，寫測試來覆蓋它，做一個新的方法來置換它。Be nice，這個任何事情都有紀錄的年代，保持中性是讓自己更專業的方法。

不寫註解的話，我們能做什麼？

好啊，大家都不要寫註解啊！那我們能做什麼？

1. 準確的命名
   把相關的命名寫好，並且適度的編寫，整個程式就會非常的口語而且容易懂。
2. 高覆蓋率的單元測試
   還記得單元測試的命名怎麼寫嗎？單元測試的案例可以更容易的讓後續的維護人員知道要注意的地方。
3. 更完整的commit log
   從簽入的記錄就可以知道程式修改的歷程，同時也可以知道修改的程式片段。後面會討論寫Commit Log要注意的地方。
4. 讓我寫！罷脫！
   雖然我不覺得寫註解很重要，但並不反對寫註解，只是要寫到重點。如果真的要寫，應該要說服團隊，討論要怎麼寫，寫的重點是什麼...等等。

最後，不要用註解程式當備份

對！這是一個非常差的習慣：用註解的方法當成備份。這是2020年了，任何程式碼都可以在版本控制系統裡找到，勇敢的把程式刪掉吧！